home *** CD-ROM | disk | FTP | other *** search
/ Workbench Add-On / Workbench Add-On - Volume 1.iso / BBS-Archive / DiskUtil / Crunch / XFH.lha / XFH / XFH.DOC < prev    next >
Text File  |  1994-05-06  |  17KB  |  376 lines
  1. ----------------------------------------------------------------------------
  2.  
  3.                XFH-Handler 1.39
  4.  
  5.        Copyright (C) 1991, 1992, 1993, 1994 Kristian Nielsen.
  6. ----------------------------------------------------------------------------
  7.  
  8.  
  9.     This program is free software; you can redistribute it and/or modify
  10.     it under the terms of the GNU General Public License as published by
  11.     the Free Software Foundation; either version 2 of the License, or
  12.     (at your option) any later version.
  13.  
  14.     This program is distributed in the hope that it will be useful,
  15.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  16.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17.     GNU General Public License for more details.
  18.  
  19.     You should have received a copy of the GNU General Public License
  20.     along with this program; if not, write to the Free Software
  21.     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  22.  
  23.  
  24. Comments, suggestions and bug reports are welcome. I can be reached as
  25.  
  26.    Kristian Nielsen
  27.    Groenjordskollegiet
  28.    room 6111
  29.    Groenjordsvej
  30.    DK-2300 Koebenhavn S
  31.    Denmark.
  32.  
  33.    E-Mail: bombadil@diku.dk
  34.  
  35.  
  36. Legal Issues
  37. ------------
  38.  
  39. This program as a whole is distributed under the GNU General Public
  40. License. However, some of the contained material carries different
  41. legal status. In particular, this product includes software developed
  42. by the University of California, Berkeley and its contributors.
  43. Details appear in each individual file in the source directories.
  44.  
  45. The "XFH" commodity was written by
  46.  
  47.    Nicola Salmoria
  48.    Via Piemonte 11
  49.    53100 Siena   ITALY
  50.  
  51.    E-Mail: MC6489@mclink.it
  52.  
  53. This program (the commodity with icons and mountlists) is freely
  54. distributable as long as the archive remains intact, and only a
  55. nominal fee is charged for its distribution. However, it is still
  56. provided "AS IS" without warranty of any kind, either expressed or
  57. implied. By using it, you agree to accept the entire risk as to the
  58. quality and performance of the program.
  59.  
  60. Version after 1.32 and "xScan" were done by:
  61.  
  62.    Matthias Scheler
  63.    Schuetzenstrasse 18
  64.    33178 Borchen
  65.    Federal Republic of Germany
  66.  
  67.    E-Mail: tron@lyssa.pb.owl.de
  68.  
  69. Changes since the previous versions
  70. -----------------------------------
  71.  
  72. Changes since last release V1.34:
  73.  - more 2.0 packets including support for hard- and softlinks
  74.  - extended builtin support for xScan
  75.  - XFH is now distributed with full source code for SAS/C Release 6.51.
  76.  - kludge to get XFH to work on top of Envoy FS
  77.  
  78. Changes since last release V1.32:
  79.  - After using the supplied tool "xScan" XFH will read directories MUCH
  80.    faster. Read "xScan.doc" for information about that.
  81.  - XFH now supports ACTION_PARENT_FH. Now MultiView and "amigaguide.datatype"
  82.    have no more problems to use links between different AmigaGuide files.
  83.  - XFH is now distributed with full source code for SAS/C Release 6.
  84.  
  85. Important changes include since V1.12:
  86.  - XFH is now distributed with full source code (for GCC).
  87.  - The dreaded 'ExNext() / ExAll() bug with filenotes has been fixed.
  88.  - Much improved user interface: Gui 'front panel' (by Nicola
  89.    Salmoria), improved mountlist control.
  90.  - Arexx interface for setting options after mounting the handler.
  91.  - Support for MODE_READWRITE (appending to files).
  92.  
  93. Overview
  94. --------
  95.  
  96. XFH-handler is a DOS handler which uses xpkmaster.library to provide
  97. transparent access to compressed files in a given directory or partition.
  98. All compression/decompression is done automatically by the handler when files
  99. are read or written. Compression is optional and may be switched at any time,
  100. allowing for fine control over storage of data. The compression method may be
  101. changed at will. Decompression is always automatic, you don't have to care
  102. about which compressor was used to create the files.
  103.  
  104. This version of XFH is designed to work with Xpk, the data compression
  105. standard. You will need Xpk to use XFH. Most users should receive XFH as part
  106. of the Xpk distribution.
  107.  
  108. [Notes for users of previous versions of XFH: The way the handler is mounted
  109. has changed somewhat since v1.12 in order to make it simpler to use; you
  110. cannot just replace the binary in L: and go. This doc file does not mention
  111. the old option files, but they can still be used if you want to. Refer to the
  112. file "advanced_usage.doc". Also note that XFH now supports updating of
  113. existing files, something that a lot of users have requested.]
  114.  
  115.  
  116. Installation
  117. ------------
  118.  
  119. This doc file is intended for Workbench 2.0 or later. If you are using
  120. Wb 1.x, refer to "advanced_usage.doc". That file contains also information
  121. which may be useful to the advanced user.
  122.  
  123. We have tried to make the installation of XFH as easy as possible, but it
  124. still isn't a trivial task. Please read this paragraph carefully.
  125.  
  126. First of all, you will need to have xpkmaster.library installed
  127. (xpkmaster.library is distributed as part of Xpk). Refer to xpkmaster
  128. documentation for installation. Version 2.2 (or any later version) of
  129. xpkmaster.library is suggested, since previous versions contain some bugs
  130. which may make XFH behave incorrectly.
  131.  
  132. Then, copy "XFH-Handler" to your L: directory, and drag "XFH" into the
  133. Wbstartup drawer. XFH is a commodity, so as usual you will want to change
  134. the CX_POPUP ToolType from YES to NO to avoid having the window open
  135. everytime you boot.
  136.  
  137. Now you have to decide which partition you want to install XFH upon. Of
  138. course you can choose more than one partition, but with this version of XFH
  139. you shouldn't use the boot partition unless you really know what you are
  140. doing.
  141. >> NEVER COMPRESS XFH-HANDLER, XPKMASTER.LIBRARY, MOUNT, OR ANY OTHER FILE
  142. NEEDED TO MAKE XFH WORK!!!!!! <<
  143.  
  144. You are not limited to install on full partitions; you can choose any
  145. directory, but usage on a whole partition is probably the more immediate and
  146. useful. Here, we will assume installation on a whole partition. Installation
  147. over a directory is accomplished in a similar way, or by modifying the
  148. mountlist entry as explained in "advanced_usage.doc".
  149.  
  150. If you are using Workbench 2.1 or later, drag the icon "XDH1" from the
  151. "Workbench2.1+" drawer to the "Devs/DOSDrivers" drawer in your boot
  152. partition.  As its name suggests, XDH1 will work on your DH1 partition.
  153. To choose a different partition, just rename the icon; for example, "XJH2"
  154. will refer to JH2:, and so on (in fact any letter will work, not just
  155. 'X').  You can also use assigned names; for example, let's say you have
  156. assigned DOCS: to DH2:text/docs, then a copy of the icon named "XDOCS"
  157. will create an XFH task using that directory. To create multiple XFH
  158. partitions, use the Workbench 'Copy' command to duplicate the "XDH1" icon
  159. and rename it appropriately (ie. to "XDH2"). No other changes are needed.
  160.  
  161. If you are not using Wb 2.1 yet, you will have to append the sample entry
  162. "devs/mountlist.xdh1" to your "DEVS:Mountlist" file (appending one copy for
  163. each XFH partition you wish to use). The same considerations made before
  164. apply: to change the target partition, edit the mountlist and change the
  165. XDH1: line appropriately. Then edit the file "S:User-Startup" and add lines
  166. like
  167.  
  168.     Mount XDH1:
  169.  
  170. to automatically mount the XFH partitions at boot time.
  171.  
  172. If you don't like names like XDH1, refer to "advanced_usage.doc" for a way
  173. to use a name of your choice (by modifying the mount entry).
  174.  
  175.  
  176. When mounted, XFH will display a new icon on your Workbench screen. For
  177. example, let's say that your DH1: partition is labelled "DATA"; XFH will call
  178. its partition XFH_DATA. After the first installation, you may relabel the
  179. volume as usual (XFH will use a file called '.xfhrc' in its root
  180. directory to preserve the volume name across reboots).
  181.  
  182. The first step of installation is completed. Now reset and check that
  183. everyting works correctly. Next steps assume that you have rebooted and
  184. everything was ok.
  185.  
  186.  
  187. By default, XFH doesn't compress files. To do that, invoke the XFH commodity
  188. by using the hotkey (default is control alt x) or by double-clicking its
  189. icon.  You will be shown a list of all mounted XFH partitions. Choose one,
  190. and activate the "Compression" checkbox. Now click on "Select Compressor..."
  191. button, and you will see a list of available Xpk compressors. Select your
  192. favourite compressor and efficiency and click on "OK". Currently, the best
  193. choice is probably NUKE, since it features good compression percentage and
  194. very fast decompression.
  195.  
  196. The "Low Memory" checkbox, when activated, tells XFH to reduce memory usage
  197. as much as possible, even if that means reducing speed or compression
  198. efficiency (this option is not fully implemented in the current version of
  199. XFH-Handler).
  200.  
  201.  When you have set up all the partitions, select "Save" from the
  202. "Project" menu if you want to make the changes permanent, and click in the
  203. close gadget to hide the window ("Save" will store the settings in the .info file of the commodity).
  204.  
  205. Now installation should be finished! Try to copy something to XDH1:, and try
  206. from CLI to 'list' it in DH1: and in XDH1: to see if it has actually been
  207. compressed (of course the file in DH1: should be shorter than the file which
  208. is seen thru XDH1:).
  209.  
  210. Hint: if you want to compress all the files in your new XFH partition, the
  211. faster way is to make a backup and restore of XDH1:.
  212.  
  213.  
  214. Limitations
  215. -----------
  216.  
  217. It should be stressed that a given XFH partition binds to a volume,
  218. not to a device. This has consequences if XFH is used on a removable
  219. media like a floppy disk. For example, trying to use XDF0 to access DF0
  220. will work, but it will use the disk that was in the drive at the time
  221. it was mounted and will not recognise a newly inserted disk.
  222.  
  223.    The figures reported by the shell 'Info' command are somewhat
  224. strange.  The problem is that it isn't really possible to give
  225. sensible figures for 'NumBlocks' and 'NumBlocksUsed' (except scanning
  226. the entire XFH partition which would be ridicously slow). Currently,
  227. their values are the same as those for the underlying file system.
  228.  
  229.  
  230. Suggestions
  231. -----------
  232.  
  233. Remember that, in this release of XFH-Handler, the decompressed file has to
  234. stay in memory for all the time the file is open. If you are low on memory,
  235. do not compress large files.
  236. Do not compress files which stay open for a long time.
  237. If you are using a printer spooler which creates temporary files on the hard
  238. disk (like PrintManager by Nicola Salmoria), make sure they are not
  239. automatically compressed by XFH (either turn compression off, or use DH1:
  240. instead of XDH1:).
  241.  
  242. You may not want to have both DATA and XFH_DATA displayed as volumes on the
  243. Workbench. To avoid that, edit "S:User-Startup" and add the line
  244.  
  245.     Assign DATA: DISMOUNT
  246.  
  247. Moreover, since you may have references to DATA: (for example some assigns)
  248. you may want to add this line also
  249.  
  250.     Assign DATA: XDH1:
  251.  
  252. which will reroute every later access to the XFH partition.  Note that to do
  253. this trick, the label of DH1: must *NOT* be DH1 or any other name conflicting
  254. with a device name. If it is your case, relabel the volume.  After the
  255. DISMOUNT trick, you will always access the XFH partition from Workbench, but
  256. you will still be able to use both DH1: and XDH1: from CLI.
  257.  
  258. When doing backups, use DH1:, not XDH1:. This way you will use the
  259. compressed data, thus requiring less disks. If your backup program provides
  260. compression, turn the option off, since it will only slow things down.
  261. Remember also to RESTORE to DH1:, or you will end up with a useless
  262. partition!
  263.  
  264.  
  265. Future Enhancements
  266. -------------------
  267.  
  268. The following are a few loose ideas that may sometime be realised in future
  269. versions of XFH:
  270.  
  271.  - Support for other file formats. XFH is currently dependent on Xpk for
  272. operation; however original aim was (and still is) a general compressor
  273. front-end supporting Xpk, Zoo, Lharc, Lha etc.
  274.  
  275.  - Support for custom formats through AREXX. This would make it possible to
  276. write simple AREXX scripts that are called by XFH each time a request is made
  277. to open a file that XFH does not recognise. The script can then take over if
  278. it can handle the file and call the appropriate conversion programs. Thus,
  279. one could take for example a standard gif-to-iff converter and write a simple
  280. AREXX script that would make DeluxePaint suddenly read GIF pictures
  281.  
  282.  - Setting of options individually for specific directories and/or
  283. files (using AmigaDOS pattern matching). This would make it possible
  284. to specify that files named '#?.lzh' must not be compressed, or that
  285. directory listnings of ':net/uucp/news/' should not report the correct
  286. file sizes (for speedup).
  287.  
  288.  - Making the handler multi-treaded (like the ROM file systems)
  289. (multi-treadedness means that a large Read()-request won't block a simple CD
  290. command).
  291.  
  292.  - Implementing asyncronous I/O for compression and decompression
  293. (overlapping CPU time with IO time for large speedups).
  294.  
  295.  
  296. Acknowledgments
  297. ---------------
  298.  
  299. XFH owes a lot to all the people that have helped me during development with
  300. discussions, criticism, suggestions, bug reports etc. (not to mention the
  301. steady demands for new versions when I was a bit slow bringing them out...).
  302. I am especially indebted to Nicola Salmoria who wrote the nice gui front-end
  303. to XFH, wrote most of this doc file and spent a lot of time discussing the
  304. user interface of XFH with me. Many of the improvements in user-friendliness
  305. since XFH 1.0 should be attributed to Nicola; any remaining inconveniences or
  306. bugs are entirely due to me. My thanks should also go to Urban D. Müller for
  307. helping me start the whole concept of the XFH back in the summer of 1991 -
  308. without his help the XFH is not likely to have been realised.
  309.  
  310. XFH has been developed concurrently with my studies at the University of
  311. Copenhagen, Department of Computer Science. The institute kindly provides
  312. students with access to electronic mail and news; this also has been
  313. essential in the creation of XFH.
  314.  
  315. Program history
  316. ---------------
  317.  
  318. (In the list, an asterix ('*') denotes BETA version that have not been
  319. released and should not be used).
  320.  
  321. V1.00   Initial release.
  322. V1.00a  Bug in XObjExamine() fixed (it sometimes got the name of the root
  323.         dir wrong). Thanks to Matthias Scheler for reporting this bug.
  324. V1.00b  XFH: now obtains the values returned by ACTION_INFO and
  325.         ACTION_DISK_INFO from the underlying file system. This should
  326.         help problems with 'zero size file system' as experienced with
  327.         earlier versions of MFR for example. Thanks to Keith H. Brown
  328.         for pointing my attention to this problem.
  329. V1.10*  Beta version implementing option files and automatic compression.
  330. V1.11*  Beta with Xpk password support.
  331. V1.12   New XPKPRIORITY option. Also fixes bugs with bad volume names and a 
  332.         msgport that was unnessesarely public; thanks to Nicola Salmoria 
  333.         for telling me about these problem. 
  334. V1.20*  First beta with GUI and Arexx support.
  335. V1.21*  - Bug fix: Write() to a compressed file opened for reading now
  336.         fails with a return value of -1L (it used to return 0). Thanks to
  337.         Stefan Boberg for pointing me to this problem.
  338.         - Bug fix: Very nasty bug with file notes that caused XFH to crash
  339.         the system (happened because dos.library does not preserve the
  340.         fib->fib_Comment field between calls to ExNext()). Thanks to
  341.         Anders Holmér for taking the bother sending me "snail mail" to
  342.         let me know of this problem.
  343. V1.22*    Enhanced GUI support. XFH now mounts as a handler (instead of as a
  344.     disk-device based file system). Setting of options in mountlist.
  345. V1.23*    Minor bugfixes; some options to help compatibility with various
  346.     programs.
  347. V1.30*    First version with support for MODE_READWRITE. XFH will now retain
  348.     protection flags, filenotes and file dates when compressing files.
  349.     ALLOWAPPEND and COMPRESSREADWRITE option. Write() to MODE_OLDFILE
  350.     files.
  351. V1.31*    ACTION_RENAME_DISK; PORTNAME option; minor bug fixes.
  352. V1.32     Full source provided now under GNU GPL. Source now uses RCS.
  353.     Changed default for option ALLOWAPPEND to ON. Also changed
  354.     option KILLSTARTUP to ON per default (the enforcer hits in
  355.     Format etc. were too bad).
  356. V1.33*    ACTION_PARENT_FH required for "MultiView" and "amigaguide.datatype"
  357.     done by Matthias Scheler
  358. V1.34    support for xScan, source now for SAS/C Release 6
  359.     done by Matthias Scheler
  360. V1.35*    ACTION_EXAMINE_FH required for "gzip". Reduced code size (sprintf()
  361.     via exec.library), source now for SAS/C Release 6.51. Debugging output
  362.     is now done via KPrintF() so you can use "sushi" to intercept it.
  363.     done by Matthias Scheler
  364. V1.36*    ACTION_MAKE_LINK and ACTION_READ_LINK for hard- and softlink support
  365.     done by Matthias Scheler
  366. V1.37*    comments for fast directory scan are now created automatically
  367.     (option XSCAN)
  368.     done by Matthias Scheler
  369. V1.38    added work arround for Envoy's buggy ACTION_FH_FROM_LOCK
  370.     (option ENVOYKLUDGE)
  371.     done by Matthias Scheler
  372. V1.39    Fixed bug in builtin XSCAN support (V1.37) which caused XFH to crash
  373.     with error 87000004 sometimes. Thanks to Michael Sülmann for the final
  374.     hint about this bug.
  375.     done by Matthias Scheler
  376.